Get docusaurus building #1434
Get docusaurus building #1434
Conversation
|
I think moving docs/ into website/ might be a step too far... but I'll leave @kriswest to think about that |
There was a problem hiding this comment.
I see an issue in the schema handling: docs pages when generated should point to the 'next' version of schemas. Then the versioning scripts should generate copies of those pages, copies of the schemas and update links from one to the other so we get frozen versions of both associated with each other.
See all the package.json scripts that start with version - I think the paths are all still correct as I think those all operate off the website/static folder paths... However, the copy-schemas and copy-appd scripts definitely now have incorrect paths in them. This page: https://fdc3.finos.org/schemas/next/app-directory.html may be broken in your version... Try deleting this file: https://github.com/InteropIO/FDC3/blob/monorepo-docusaurus/website/static/schemas/next/appd.schema.json
then build and if the file doesn't get replaced its broken.
For testing context schemas try the schema link any page in the next version - but watch out for URL hardcoded to their production values, you'll need to sub-in the local or preview origin. Same goes for API schemas in the new 'specs' pages.
It'd also be helpful to have a quick word in teh PR description on why moving docs into the website folder helps (I do know its the normal pattern for a docusaurus site). The license covering said docs (the CSL) remains in the root directory. 'The Standard' is essentially the docs and schema files - the schema files now reside in /packages/fdc3-schema and /packages/fdc3-context and appear to be under the Apache-2.0 license (as thats whats in their package.json files).
@robmoffat I don't actually know the licensing implications here. The schemas contain information that is not in the docs and need to be a formally under the CSL, as do the docs. If this is problematic, it is so in both cases - perhaps worse in the schema packages as they explicitly state a different license...
Docusaurus is pretty opinionated on where the docs files should live. There were a bunch of build errors that just disappeared once I moved the files into the folder docusaurus likes them to be in. If you want the docs folder to stay separate, I assume that you can, but there's going to be a lot of juggling on someone's part. |
Hmm, thats odd as AFAIK we aren't getting build errors in the pre-refactor version with docs up a level and the docusaurus config pointing at them. Got any details on the errors (out of interest)? Or any details on the juggling needed if we don't do it? |
|
Oh and we've got this PR hanging out there as part of the Citi Hackathon, which is trying to upgrade existing docs to work in Docusaurus 3: #1418 I'd guess we'll have to make some similar changes for anything introduced since then. I can ask them to rebase on main as the fdc3 for web docs just got merged in. |
|
I've updated the copy/paste scripts to move the schemas from the correct place. |
Thanks @julianna-ciq, don't forget to run schema2markdown again, it should drop a bunch of the context docs pages from the diff (currently 217 files) by eliminating the change to the schema URL. I'm seeing some additional differences in the context docs pages that are reverting recent changes, e.g. instrumentList losing its id and name properties: Those should vanish as well, thats probably a result of generating from the 2.1 schemas instead of next 🤞 |
|
@robmoffat and @julianna-ciq I only see one issue with moving the docs folder into /website and that is the docusaurus v3 update PR #1418. @julianna-ciq has done the move correctly so that should merge with this just fine. We just need to get #1418 updated from main, with any additional fixes for recently merged context applied and then merged and we should be good to go. I would say its safe to merge this into fdc3-for-web-impl while we get #1418 updated and merged. |
|
can you re-review? It won't let me merge it until you're not "requesting changes" |
No description provided.